/**
 * javax.servlet包中含有许多类和接口,他们描述并定义了在servlet类和实例之间的通信约定.
 */
 
package javax.servlet;

import java.io.IOException;


/**
 * servlet实例必须实现接口中定义的所有方法.
 *
 * <p>servlet是一个运行在web服务器上的java小程序.Servlet接收并响应来自Web客户端的请求,
 * 
 * 通常客户端发送过来的请求都是基于HTTP协议的,即超文本传输协议.
 * 
 *
 * <p>想要实现这个接口,你可以写一个继承自<code>javax.servlet.GenericServlet</code>的通用servlet
 * 
 * 或一个继承自<code>javax.servlet.http.HttpServlet</code>的HTTP servlet.
 *
 * <p>接口定义了初始化servlet,响应客户端请求,以及从服务器上删除servlet的方法.
 * 
 * 这些方法被认为是Servlet生命周期(Servlet生命周期就是指Servlet实例在创建之后响应客户请求直至销毁的全过程)方法,方法通常按以下次序进行调用:
 * 
 * <ol>
 * 	 <li>servlet完成构造后,然后调用<code>init</code>方法进行初始化. 
 * 	 <li>来自客户端的所有请求都会交由<code>service</code>方法来处理.
 * 	 <li>servlet停止服务, 然后调用<code>destroy</code>方法销毁对象,
 * 			最终由垃圾回收器来完成资源释放工作.
 * </ol>
 *
 *
 *
 * <p>除生命周期方法之外,此接口还提供<code>getServletConfig</code>方法
 * 	和<code>getServletInfo</code>方法,
 * 	servlet实例可以使用<code>getServletConfig</code>方法获得所有<br/>启动信息,
 * 	而<code>getServletInfo</code>方法允许servlet返回一些与其Sevlet容器相关的基本信息,
 * 	例如作者、版本、版权...
 *
 * @author 	Various
 * @version 	$Version$
 *
 * @see 	GenericServlet
 * @see 	javax.servlet.http.HttpServlet
 *
 */


public interface Servlet {

    /**  
     * servlet容器调用此方法,将servlet装载到servlet容器的服务队列中.
     *
     * <p>Serlvet容器在实例化servlet(指创建实现了Servlet接口的类的实例)之后,只能正确地调用<code>init</code>方法一次. 
     * 
     * 在servlet能够接受任何请求之前,init方法必须成功完成初始化工作.
     * 
     *
     * <p>如果<code>init</code>方法没成功完成初始化,
     * Sevlet容器将无法将servlet装载到服务中,则直接卸载该实例.
     * <ol>
     * <li>抛出 <code>ServletException</code>
     * <li>Does not return within a time period defined by the Web server
     * </ol>
     *
     * 
     * @param config 一个含有servlet配置和初始化参数的<code>ServletConfig</code>对象
     *
     * @exception ServletException 	由servlet接口常规操作引发的异常
     *					
     *					
     *
     * @see 				UnavailableException
     * @see 				#getServletConfig
     *
     */

    public void init(ServletConfig config) throws ServletException;
    
    /**
     *
     * 返回一个包含当前servlet初始化信息和启动参数的{@link ServletConfig}对象.
     * 返回的<code>ServletConfig</code>对象就是<code>init</code>方法传入的那个实例.
     * 

     * <p>实现此接口类的目的就是为了存储<code>ServletConfig</code>对象,以便该方法能够返回一个<code>ServletConfig</code>对象的实例.
     * {@link GenericServlet}类已实现此接口,
     * 并且已经实现这个方法.
     *
     * @return		初始化当前servlet的<code>ServletConfig</code>的对象
     *			 
     *
     * @see 		#init
     *
     */

    public ServletConfig getServletConfig();
    
    
    /**
     * servlet容器调用此方法让servlet容器响应客户端请求. 
     * 
     *  
     * <p>方法只能在servlet的<code>init()</code>方法成功初始化后才能被调用.
     * 
     * <p>响应状态代码通常以servlet抛出或发送一个预先定义的错误代码的方式发送给客户端.
     *
     *	
     *  
     * 
     * <p>Servlets是典型的运行在多线程servlet容器内部的,
     * 可以并发处理多部请求的java程序,
     * 客户端开发人员必须有意识的同步访问所有共享资源,
     * 例如文件、网络连接以及Servlet的类和实例变量.
     * 
     * 
     * 更多相关Java多线程编程信息请参考 
     * <a href="http://java.sun.com/Series/Tutorial/java/threads/multithreaded.html">
     * the Java tutorial on multi-threaded programming</a>.
     *
     *
     * @param req 	携带客户端请求描述的<code>ServletRequest</code>对象 
     *			
     *	
     * @param res 	携带servlet返回请求结果的<code>ServletResponse</code>对象 
     *			
     *
     * @exception ServletException 	由servlet接口常规操作引发的异常
     *					
     *
     * @exception IOException 		如果发生输入或输出错误
     *
     */

    public void service(ServletRequest req, ServletResponse res)
	throws ServletException, IOException;
	
   

    /**
     * 返回与Sevlet相关的信息,例如作者、版本、版权...
     * 
     * <p>此方法返回的字符串应该是纯文本格式的并且不含任何标签(例如 HTML,XML等).
     * 
     * @return 	含有Servlet信息的<code>String</code>
     *
     */

    public String getServletInfo();

    /**
     *
     * servlet容器调用此方法,清理所有挂起资源(例如,内存文件句柄,线程),表示Servlet正被清除出服务.
     * 方法当且仅当在Servlet的<code>service</code>
     * 方法中所有线程已退出或service方法已调用后的一段时间后(等待服务器设定超时值到达后)调用.
     * Servlet容器调用此方法后,Servlet就不可以再调用 <code>service</code>方法了.
     * 
     */

    public void destroy();
}
